
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Writing and running tests &#8212; Django 1.11.22.dev20190603194737 documentation</title>
    <link rel="stylesheet" href="../../_static/default.css" type="text/css" />
    <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
    <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
    <script type="text/javascript" src="../../_static/jquery.js"></script>
    <script type="text/javascript" src="../../_static/underscore.js"></script>
    <script type="text/javascript" src="../../_static/doctools.js"></script>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="Testing tools" href="tools.html" />
    <link rel="prev" title="Testing in Django" href="index.html" />



 
<script type="text/javascript" src="../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
    if (!django_template_builtins) {
       // templatebuiltins.js missing, do nothing.
       return;
    }
    $(document).ready(function() {
        // Hyperlink Django template tags and filters
        var base = "../../ref/templates/builtins.html";
        if (base == "#") {
            // Special case for builtins.html itself
            base = "";
        }
        // Tags are keywords, class '.k'
        $("div.highlight\\-html\\+django span.k").each(function(i, elem) {
             var tagname = $(elem).text();
             if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
                 var fragment = tagname.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
             }
        });
        // Filters are functions, class '.nf'
        $("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
             var filtername = $(elem).text();
             if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
                 var fragment = filtername.replace(/_/, '-');
                 $(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
             }
        });
    });
})(jQuery);
</script>


  </head><body>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 1.11.22.dev20190603194737 documentation</a></h1>
      <div id="global-nav">
        <a title="Home page" href="../../index.html">Home</a>  |
        <a title="Table of contents" href="../../contents.html">Table of contents</a>  |
        <a title="Global index" href="../../genindex.html">Index</a>  |
        <a title="Module index" href="../../py-modindex.html">Modules</a>
      </div>
      <div class="nav">
    &laquo; <a href="index.html" title="Testing in Django">previous</a>
     |
    <a href="../index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="tools.html" title="Testing tools">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="topics-testing-overview">
            
  <div class="section" id="s-module-django.test">
<span id="s-writing-and-running-tests"></span><span id="module-django.test"></span><span id="writing-and-running-tests"></span><h1>Writing and running tests<a class="headerlink" href="#module-django.test" title="Permalink to this headline">¶</a></h1>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The <a class="reference internal" href="../../intro/tutorial05.html"><span class="doc">testing tutorial</span></a>, the <a class="reference internal" href="tools.html"><span class="doc">testing tools
reference</span></a>, and the <a class="reference internal" href="advanced.html"><span class="doc">advanced testing topics</span></a>.</p>
</div>
<p>This document is split into two primary sections. First, we explain how to write
tests with Django. Then, we explain how to run them.</p>
<div class="section" id="s-writing-tests">
<span id="writing-tests"></span><h2>Writing tests<a class="headerlink" href="#writing-tests" title="Permalink to this headline">¶</a></h2>
<p>Django’s unit tests use a Python standard library module: <a class="reference external" href="https://docs.python.org/3/library/unittest.html#module-unittest" title="(in Python v3.7)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a>. This
module defines tests using a class-based approach.</p>
<p>Here is an example which subclasses from <a class="reference internal" href="tools.html#django.test.TestCase" title="django.test.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.test.TestCase</span></code></a>,
which is a subclass of <a class="reference external" href="https://docs.python.org/3/library/unittest.html#unittest.TestCase" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a> that runs each test inside a
transaction to provide isolation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.test</span> <span class="k">import</span> <span class="n">TestCase</span>
<span class="kn">from</span> <span class="nn">myapp.models</span> <span class="k">import</span> <span class="n">Animal</span>

<span class="k">class</span> <span class="nc">AnimalTestCase</span><span class="p">(</span><span class="n">TestCase</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">Animal</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;lion&quot;</span><span class="p">,</span> <span class="n">sound</span><span class="o">=</span><span class="s2">&quot;roar&quot;</span><span class="p">)</span>
        <span class="n">Animal</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">create</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;cat&quot;</span><span class="p">,</span> <span class="n">sound</span><span class="o">=</span><span class="s2">&quot;meow&quot;</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">test_animals_can_speak</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;Animals that can speak are correctly identified&quot;&quot;&quot;</span>
        <span class="n">lion</span> <span class="o">=</span> <span class="n">Animal</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;lion&quot;</span><span class="p">)</span>
        <span class="n">cat</span> <span class="o">=</span> <span class="n">Animal</span><span class="o">.</span><span class="n">objects</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="n">name</span><span class="o">=</span><span class="s2">&quot;cat&quot;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">lion</span><span class="o">.</span><span class="n">speak</span><span class="p">(),</span> <span class="s1">&#39;The lion says &quot;roar&quot;&#39;</span><span class="p">)</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">cat</span><span class="o">.</span><span class="n">speak</span><span class="p">(),</span> <span class="s1">&#39;The cat says &quot;meow&quot;&#39;</span><span class="p">)</span>
</pre></div>
</div>
<p>When you <a class="reference internal" href="#running-tests"><span class="std std-ref">run your tests</span></a>, the default behavior of the
test utility is to find all the test cases (that is, subclasses of
<a class="reference external" href="https://docs.python.org/3/library/unittest.html#unittest.TestCase" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a>) in any file whose name begins with <code class="docutils literal notranslate"><span class="pre">test</span></code>,
automatically build a test suite out of those test cases, and run that suite.</p>
<p>For more details about <a class="reference external" href="https://docs.python.org/3/library/unittest.html#module-unittest" title="(in Python v3.7)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a>, see the Python documentation.</p>
<div class="admonition-where-should-the-tests-live admonition">
<p class="first admonition-title">Where should the tests live?</p>
<p>The default <a class="reference internal" href="../../ref/django-admin.html#django-admin-startapp"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">startapp</span></code></a> template creates a <code class="docutils literal notranslate"><span class="pre">tests.py</span></code> file in the
new application. This might be fine if you only have a few tests, but as
your test suite grows you’ll likely want to restructure it into a tests
package so you can split your tests into different submodules such as
<code class="docutils literal notranslate"><span class="pre">test_models.py</span></code>, <code class="docutils literal notranslate"><span class="pre">test_views.py</span></code>, <code class="docutils literal notranslate"><span class="pre">test_forms.py</span></code>, etc. Feel free to
pick whatever organizational scheme you like.</p>
<p class="last">See also <a class="reference internal" href="advanced.html#testing-reusable-applications"><span class="std std-ref">Using the Django test runner to test reusable applications</span></a>.</p>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>If your tests rely on database access such as creating or querying models,
be sure to create your test classes as subclasses of
<a class="reference internal" href="tools.html#django.test.TestCase" title="django.test.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.test.TestCase</span></code></a> rather than <a class="reference external" href="https://docs.python.org/3/library/unittest.html#unittest.TestCase" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a>.</p>
<p class="last">Using <a class="reference external" href="https://docs.python.org/3/library/unittest.html#unittest.TestCase" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a> avoids the cost of running each test in a
transaction and flushing the database, but if your tests interact with
the database their behavior will vary based on the order that the test
runner executes them. This can lead to unit tests that pass when run in
isolation but fail when run in a suite.</p>
</div>
</div>
<div class="section" id="s-running-tests">
<span id="s-id1"></span><span id="running-tests"></span><span id="id1"></span><h2>Running tests<a class="headerlink" href="#running-tests" title="Permalink to this headline">¶</a></h2>
<p>Once you’ve written tests, run them using the <a class="reference internal" href="../../ref/django-admin.html#django-admin-test"><code class="xref std std-djadmin docutils literal notranslate"><span class="pre">test</span></code></a> command of
your project’s <code class="docutils literal notranslate"><span class="pre">manage.py</span></code> utility:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./manage.py test
</pre></div>
</div>
<p>Test discovery is based on the unittest module’s <a class="reference external" href="https://docs.python.org/3/library/unittest.html#unittest-test-discovery" title="(in Python v3.7)"><span class="xref std std-ref">built-in test
discovery</span></a>.  By default, this will discover tests in
any file named “test*.py” under the current working directory.</p>
<p>You can specify particular tests to run by supplying any number of “test
labels” to <code class="docutils literal notranslate"><span class="pre">./manage.py</span> <span class="pre">test</span></code>. Each test label can be a full Python dotted
path to a package, module, <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> subclass, or test method. For instance:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span># Run all the tests in the animals.tests module
$ ./manage.py test animals.tests

# Run all the tests found within the &#39;animals&#39; package
$ ./manage.py test animals

# Run just one test case
$ ./manage.py test animals.tests.AnimalTestCase

# Run just one test method
$ ./manage.py test animals.tests.AnimalTestCase.test_animals_can_speak
</pre></div>
</div>
<p>You can also provide a path to a directory to discover tests below that
directory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./manage.py test animals/
</pre></div>
</div>
<p>You can specify a custom filename pattern match using the <code class="docutils literal notranslate"><span class="pre">-p</span></code> (or
<code class="docutils literal notranslate"><span class="pre">--pattern</span></code>) option, if your test files are named differently from the
<code class="docutils literal notranslate"><span class="pre">test*.py</span></code> pattern:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ ./manage.py test --pattern=&quot;tests_*.py&quot;
</pre></div>
</div>
<p>If you press <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> while the tests are running, the test runner will
wait for the currently running test to complete and then exit gracefully.
During a graceful exit the test runner will output details of any test
failures, report on how many tests were run and how many errors and failures
were encountered, and destroy any test databases as usual. Thus pressing
<code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> can be very useful if you forget to pass the <a class="reference internal" href="../../ref/django-admin.html#cmdoption-test-failfast"><code class="xref std std-option docutils literal notranslate"><span class="pre">--failfast</span></code></a> option, notice that some tests are unexpectedly failing and
want to get details on the failures without waiting for the full test run to
complete.</p>
<p>If you do not want to wait for the currently running test to finish, you
can press <code class="docutils literal notranslate"><span class="pre">Ctrl-C</span></code> a second time and the test run will halt immediately,
but not gracefully. No details of the tests run before the interruption will
be reported, and any test databases created by the run will not be destroyed.</p>
<div class="admonition-test-with-warnings-enabled admonition">
<p class="first admonition-title">Test with warnings enabled</p>
<p class="last">It’s a good idea to run your tests with Python warnings enabled:
<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-Wall</span> <span class="pre">manage.py</span> <span class="pre">test</span></code>. The <code class="docutils literal notranslate"><span class="pre">-Wall</span></code> flag tells Python to
display deprecation warnings. Django, like many other Python libraries,
uses these warnings to flag when features are going away. It also might
flag areas in your code that aren’t strictly wrong but could benefit
from a better implementation.</p>
</div>
<div class="section" id="s-the-test-database">
<span id="s-id2"></span><span id="the-test-database"></span><span id="id2"></span><h3>The test database<a class="headerlink" href="#the-test-database" title="Permalink to this headline">¶</a></h3>
<p>Tests that require a database (namely, model tests) will not use your “real”
(production) database. Separate, blank databases are created for the tests.</p>
<p>Regardless of whether the tests pass or fail, the test databases are destroyed
when all the tests have been executed.</p>
<p>You can prevent the test databases from being destroyed by using the
<a class="reference internal" href="../../ref/django-admin.html#cmdoption-test-keepdb"><code class="xref std std-option docutils literal notranslate"><span class="pre">test</span> <span class="pre">--keepdb</span></code></a> option. This will preserve the test database between
runs. If the database does not exist, it will first be created. Any migrations
will also be applied in order to keep it up to date.</p>
<p>The default test database names are created by prepending <code class="docutils literal notranslate"><span class="pre">test_</span></code> to the
value of each <a class="reference internal" href="../../ref/settings.html#std:setting-NAME"><code class="xref std std-setting docutils literal notranslate"><span class="pre">NAME</span></code></a> in <a class="reference internal" href="../../ref/settings.html#std:setting-DATABASES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DATABASES</span></code></a>. When using SQLite, the
tests will use an in-memory database by default (i.e., the database will be
created in memory, bypassing the filesystem entirely!). The <a class="reference internal" href="../../ref/settings.html#std:setting-DATABASE-TEST"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEST</span></code></a> dictionary in <a class="reference internal" href="../../ref/settings.html#std:setting-DATABASES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DATABASES</span></code></a> offers a number of settings
to configure your test database. For example, if you want to use a different
database name, specify <a class="reference internal" href="../../ref/settings.html#std:setting-TEST_NAME"><code class="xref std std-setting docutils literal notranslate"><span class="pre">NAME</span></code></a> in the <a class="reference internal" href="../../ref/settings.html#std:setting-DATABASE-TEST"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEST</span></code></a> dictionary for any given database in <a class="reference internal" href="../../ref/settings.html#std:setting-DATABASES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DATABASES</span></code></a>.</p>
<p>On PostgreSQL, <a class="reference internal" href="../../ref/settings.html#std:setting-USER"><code class="xref std std-setting docutils literal notranslate"><span class="pre">USER</span></code></a> will also need read access to the built-in
<code class="docutils literal notranslate"><span class="pre">postgres</span></code> database.</p>
<p>Aside from using a separate database, the test runner will otherwise
use all of the same database settings you have in your settings file:
<a class="reference internal" href="../../ref/settings.html#std:setting-DATABASE-ENGINE"><code class="xref std std-setting docutils literal notranslate"><span class="pre">ENGINE</span></code></a>, <a class="reference internal" href="../../ref/settings.html#std:setting-USER"><code class="xref std std-setting docutils literal notranslate"><span class="pre">USER</span></code></a>, <a class="reference internal" href="../../ref/settings.html#std:setting-HOST"><code class="xref std std-setting docutils literal notranslate"><span class="pre">HOST</span></code></a>, etc. The
test database is created by the user specified by <a class="reference internal" href="../../ref/settings.html#std:setting-USER"><code class="xref std std-setting docutils literal notranslate"><span class="pre">USER</span></code></a>, so you’ll
need to make sure that the given user account has sufficient privileges to
create a new database on the system.</p>
<p>For fine-grained control over the character encoding of your test
database, use the <a class="reference internal" href="../../ref/settings.html#std:setting-TEST_CHARSET"><code class="xref std std-setting docutils literal notranslate"><span class="pre">CHARSET</span></code></a> TEST option. If you’re using
MySQL, you can also use the <a class="reference internal" href="../../ref/settings.html#std:setting-TEST_COLLATION"><code class="xref std std-setting docutils literal notranslate"><span class="pre">COLLATION</span></code></a> option to
control the particular collation used by the test database. See the
<a class="reference internal" href="../../ref/settings.html"><span class="doc">settings documentation</span></a> for details of these
and other advanced settings.</p>
<p>If using an SQLite in-memory database with Python 3.4+ and SQLite 3.7.13+,
<a class="reference external" href="https://www.sqlite.org/sharedcache.html">shared cache</a> will be enabled, so
you can write tests with ability to share the database between threads.</p>
<div class="admonition-finding-data-from-your-production-database-when-running-tests admonition">
<p class="first admonition-title">Finding data from your production database when running tests?</p>
<p>If your code attempts to access the database when its modules are compiled,
this will occur <em>before</em> the test database is set up, with potentially
unexpected results. For example, if you have a database query in
module-level code and a real database exists, production data could pollute
your tests. <em>It is a bad idea to have such import-time database queries in
your code</em> anyway - rewrite your code so that it doesn’t do this.</p>
<p class="last">This also applies to customized implementations of
<a class="reference internal" href="../../ref/applications.html#django.apps.AppConfig.ready" title="django.apps.AppConfig.ready"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ready()</span></code></a>.</p>
</div>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last">The <a class="reference internal" href="advanced.html#topics-testing-advanced-multidb"><span class="std std-ref">advanced multi-db testing topics</span></a>.</p>
</div>
</div>
<div class="section" id="s-order-in-which-tests-are-executed">
<span id="s-order-of-tests"></span><span id="order-in-which-tests-are-executed"></span><span id="order-of-tests"></span><h3>Order in which tests are executed<a class="headerlink" href="#order-in-which-tests-are-executed" title="Permalink to this headline">¶</a></h3>
<p>In order to guarantee that all <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> code starts with a clean database,
the Django test runner reorders tests in the following way:</p>
<ul class="simple">
<li>All <a class="reference internal" href="tools.html#django.test.TestCase" title="django.test.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TestCase</span></code></a> subclasses are run first.</li>
<li>Then, all other Django-based tests (test cases based on
<a class="reference internal" href="tools.html#django.test.SimpleTestCase" title="django.test.SimpleTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleTestCase</span></code></a>, including
<a class="reference internal" href="tools.html#django.test.TransactionTestCase" title="django.test.TransactionTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TransactionTestCase</span></code></a>) are run with no particular
ordering guaranteed nor enforced among them.</li>
<li>Then any other <a class="reference external" href="https://docs.python.org/3/library/unittest.html#unittest.TestCase" title="(in Python v3.7)"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a> tests (including doctests) that may
alter the database without restoring it to its original state are run.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The new ordering of tests may reveal unexpected dependencies on test case
ordering. This is the case with doctests that relied on state left in the
database by a given <a class="reference internal" href="tools.html#django.test.TransactionTestCase" title="django.test.TransactionTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TransactionTestCase</span></code></a> test, they
must be updated to be able to run independently.</p>
</div>
<p>You may reverse the execution order inside groups using the <a class="reference internal" href="../../ref/django-admin.html#cmdoption-test-reverse"><code class="xref std std-option docutils literal notranslate"><span class="pre">test</span>
<span class="pre">--reverse</span></code></a> option. This can help with ensuring your tests are independent from
each other.</p>
</div>
<div class="section" id="s-rollback-emulation">
<span id="s-test-case-serialized-rollback"></span><span id="rollback-emulation"></span><span id="test-case-serialized-rollback"></span><h3>Rollback emulation<a class="headerlink" href="#rollback-emulation" title="Permalink to this headline">¶</a></h3>
<p>Any initial data loaded in migrations will only be available in <code class="docutils literal notranslate"><span class="pre">TestCase</span></code>
tests and not in <code class="docutils literal notranslate"><span class="pre">TransactionTestCase</span></code> tests, and additionally only on
backends where transactions are supported (the most important exception being
MyISAM). This is also true for tests which rely on <code class="docutils literal notranslate"><span class="pre">TransactionTestCase</span></code>
such as <a class="reference internal" href="tools.html#django.test.LiveServerTestCase" title="django.test.LiveServerTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">LiveServerTestCase</span></code></a> and
<a class="reference internal" href="../../ref/contrib/staticfiles.html#django.contrib.staticfiles.testing.StaticLiveServerTestCase" title="django.contrib.staticfiles.testing.StaticLiveServerTestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">StaticLiveServerTestCase</span></code></a>.</p>
<p>Django can reload that data for you on a per-testcase basis by
setting the <code class="docutils literal notranslate"><span class="pre">serialized_rollback</span></code> option to <code class="docutils literal notranslate"><span class="pre">True</span></code> in the body of the
<code class="docutils literal notranslate"><span class="pre">TestCase</span></code> or <code class="docutils literal notranslate"><span class="pre">TransactionTestCase</span></code>, but note that this will slow down
that test suite by approximately 3x.</p>
<p>Third-party apps or those developing against MyISAM will need to set this;
in general, however, you should be developing your own projects against a
transactional database and be using <code class="docutils literal notranslate"><span class="pre">TestCase</span></code> for most tests, and thus
not need this setting.</p>
<p>The initial serialization is usually very quick, but if you wish to exclude
some apps from this process (and speed up test runs slightly), you may add
those apps to <a class="reference internal" href="../../ref/settings.html#std:setting-TEST_NON_SERIALIZED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEST_NON_SERIALIZED_APPS</span></code></a>.</p>
<p>To prevent serialized data from being loaded twice, setting
<code class="docutils literal notranslate"><span class="pre">serialized_rollback=True</span></code> disables the
<a class="reference internal" href="../../ref/signals.html#django.db.models.signals.post_migrate" title="django.db.models.signals.post_migrate"><code class="xref py py-data docutils literal notranslate"><span class="pre">post_migrate</span></code></a> signal when flushing the test
database.</p>
</div>
<div class="section" id="s-other-test-conditions">
<span id="other-test-conditions"></span><h3>Other test conditions<a class="headerlink" href="#other-test-conditions" title="Permalink to this headline">¶</a></h3>
<p>Regardless of the value of the <a class="reference internal" href="../../ref/settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DEBUG</span></code></a> setting in your configuration
file, all Django tests run with <a class="reference internal" href="../../ref/settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DEBUG</span></code></a>=False. This is to ensure that
the observed output of your code matches what will be seen in a production
setting.</p>
<p>Caches are not cleared after each test, and running “manage.py test fooapp” can
insert data from the tests into the cache of a live system if you run your
tests in production because, unlike databases, a separate “test cache” is not
used. This behavior <a class="reference external" href="https://code.djangoproject.com/ticket/11505">may change</a> in the future.</p>
</div>
<div class="section" id="s-understanding-the-test-output">
<span id="understanding-the-test-output"></span><h3>Understanding the test output<a class="headerlink" href="#understanding-the-test-output" title="Permalink to this headline">¶</a></h3>
<p>When you run your tests, you’ll see a number of messages as the test runner
prepares itself. You can control the level of detail of these messages with the
<code class="docutils literal notranslate"><span class="pre">verbosity</span></code> option on the command line:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Creating</span> <span class="n">test</span> <span class="n">database</span><span class="o">...</span>
<span class="n">Creating</span> <span class="n">table</span> <span class="n">myapp_animal</span>
<span class="n">Creating</span> <span class="n">table</span> <span class="n">myapp_mineral</span>
</pre></div>
</div>
<p>This tells you that the test runner is creating a test database, as described
in the previous section.</p>
<p>Once the test database has been created, Django will run your tests.
If everything goes well, you’ll see something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">----------------------------------------------------------------------</span>
<span class="n">Ran</span> <span class="mi">22</span> <span class="n">tests</span> <span class="ow">in</span> <span class="mf">0.221</span><span class="n">s</span>

<span class="n">OK</span>
</pre></div>
</div>
<p>If there are test failures, however, you’ll see full details about which tests
failed:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">======================================================================</span>
<span class="n">FAIL</span><span class="p">:</span> <span class="n">test_was_published_recently_with_future_poll</span> <span class="p">(</span><span class="n">polls</span><span class="o">.</span><span class="n">tests</span><span class="o">.</span><span class="n">PollMethodTests</span><span class="p">)</span>
<span class="o">----------------------------------------------------------------------</span>
<span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>
  <span class="n">File</span> <span class="s2">&quot;/dev/mysite/polls/tests.py&quot;</span><span class="p">,</span> <span class="n">line</span> <span class="mi">16</span><span class="p">,</span> <span class="ow">in</span> <span class="n">test_was_published_recently_with_future_poll</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">assertIs</span><span class="p">(</span><span class="n">future_poll</span><span class="o">.</span><span class="n">was_published_recently</span><span class="p">(),</span> <span class="kc">False</span><span class="p">)</span>
<span class="ne">AssertionError</span><span class="p">:</span> <span class="kc">True</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">False</span>

<span class="o">----------------------------------------------------------------------</span>
<span class="n">Ran</span> <span class="mi">1</span> <span class="n">test</span> <span class="ow">in</span> <span class="mf">0.003</span><span class="n">s</span>

<span class="n">FAILED</span> <span class="p">(</span><span class="n">failures</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>
</pre></div>
</div>
<p>A full explanation of this error output is beyond the scope of this document,
but it’s pretty intuitive. You can consult the documentation of Python’s
<a class="reference external" href="https://docs.python.org/3/library/unittest.html#module-unittest" title="(in Python v3.7)"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> library for details.</p>
<p>Note that the return code for the test-runner script is 1 for any number of
failed and erroneous tests. If all the tests pass, the return code is 0. This
feature is useful if you’re using the test-runner script in a shell script and
need to test for success or failure at that level.</p>
</div>
<div class="section" id="s-speeding-up-the-tests">
<span id="s-speeding-up-tests-auth-hashers"></span><span id="speeding-up-the-tests"></span><span id="speeding-up-tests-auth-hashers"></span><h3>Speeding up the tests<a class="headerlink" href="#speeding-up-the-tests" title="Permalink to this headline">¶</a></h3>
<div class="section" id="s-running-tests-in-parallel">
<span id="running-tests-in-parallel"></span><h4>Running tests in parallel<a class="headerlink" href="#running-tests-in-parallel" title="Permalink to this headline">¶</a></h4>
<p>As long as your tests are properly isolated, you can run them in parallel to
gain a speed up on multi-core hardware. See <a class="reference internal" href="../../ref/django-admin.html#cmdoption-test-parallel"><code class="xref std std-option docutils literal notranslate"><span class="pre">test</span> <span class="pre">--parallel</span></code></a>.</p>
</div>
<div class="section" id="s-password-hashing">
<span id="password-hashing"></span><h4>Password hashing<a class="headerlink" href="#password-hashing" title="Permalink to this headline">¶</a></h4>
<p>The default password hasher is rather slow by design. If you’re authenticating
many users in your tests, you may want to use a custom settings file and set
the <a class="reference internal" href="../../ref/settings.html#std:setting-PASSWORD_HASHERS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">PASSWORD_HASHERS</span></code></a> setting to a faster hashing algorithm:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">PASSWORD_HASHERS</span> <span class="o">=</span> <span class="p">[</span>
    <span class="s1">&#39;django.contrib.auth.hashers.MD5PasswordHasher&#39;</span><span class="p">,</span>
<span class="p">]</span>
</pre></div>
</div>
<p>Don’t forget to also include in <a class="reference internal" href="../../ref/settings.html#std:setting-PASSWORD_HASHERS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">PASSWORD_HASHERS</span></code></a> any hashing
algorithm used in fixtures, if any.</p>
</div>
<div class="section" id="s-preserving-the-test-database">
<span id="preserving-the-test-database"></span><h4>Preserving the test database<a class="headerlink" href="#preserving-the-test-database" title="Permalink to this headline">¶</a></h4>
<p>The <a class="reference internal" href="../../ref/django-admin.html#cmdoption-test-keepdb"><code class="xref std std-option docutils literal notranslate"><span class="pre">test</span> <span class="pre">--keepdb</span></code></a> option preserves the test database between test
runs. It skips the create and destroy actions which can greatly decrease the
time to run tests.</p>
</div>
</div>
</div>
</div>


          </div>
        </div>
      </div>
      
        
          <div class="yui-b" id="sidebar">
            
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Writing and running tests</a><ul>
<li><a class="reference internal" href="#writing-tests">Writing tests</a></li>
<li><a class="reference internal" href="#running-tests">Running tests</a><ul>
<li><a class="reference internal" href="#the-test-database">The test database</a></li>
<li><a class="reference internal" href="#order-in-which-tests-are-executed">Order in which tests are executed</a></li>
<li><a class="reference internal" href="#rollback-emulation">Rollback emulation</a></li>
<li><a class="reference internal" href="#other-test-conditions">Other test conditions</a></li>
<li><a class="reference internal" href="#understanding-the-test-output">Understanding the test output</a></li>
<li><a class="reference internal" href="#speeding-up-the-tests">Speeding up the tests</a><ul>
<li><a class="reference internal" href="#running-tests-in-parallel">Running tests in parallel</a></li>
<li><a class="reference internal" href="#password-hashing">Password hashing</a></li>
<li><a class="reference internal" href="#preserving-the-test-database">Preserving the test database</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="index.html"
                        title="previous chapter">Testing in Django</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="tools.html"
                        title="next chapter">Testing tools</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/topics/testing/overview.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Jun 03, 2019</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="index.html" title="Testing in Django">previous</a>
     |
    <a href="../index.html" title="Using Django" accesskey="U">up</a>
   |
    <a href="tools.html" title="Testing tools">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>